.TH PAK "1" "March 2014" "pak" "User Commands"
.SH NAME
pak \- Embedthis Pak -- Package Manager
.SH SYNOPSIS
.B pak
    \fB--all\fR
    \fB--cache dir\fR
    \fB--details\fR
    \fB--dir dir\fR
    \fB--force\fR
    \fB--log file:level\fR
    \fB--init\fR
    \fB--name name\fR
    \fB--nodeps\fR
    \fB--optional\fR
    \fB--paks dir\fR
    \fB--password file\fR
    \fB--quiet\fR
    \fB--silent\fR
    \fB--verbose\fR
    \fB--versions\fR
    \fB--write\fR
    \fBcommands ...\fB
.SH ""
.B Commands:
    cache packages...
    cached packages...
    config
    depend packages...
    edit key[=value]
    help
    init [name [version]]
    install packages...
    list packages...
    lockdown
    mode [debug|release|...]
    prune packages...
    publish [name endpoint email [override]]
    retract name [password]
    search packages...
    uninstall packages...
    update packages...
    upgrade packages...
    version [major|minor|patch|other]
.RE
.SH DESCRIPTION
\fBPak\fR is a package manager for application components.

.PP
.SH WHY PAK?
Existing package managers like NPM are excellent, but they are heavily focussed the needs of NodeJS and not
for non-Node applications or general application components. Pak is agnostic to its environment and can be
used to install components for any application.
.PP

.SH FEATURES
Pak has the following major features:

    . Install, list and uninstall packages into a local application
    . Manages a local cache of retrieved packages
    . Provides a global catalog to search for public packages
    . Easy upgrading packages when new versions become available
    . Automatically retrieves and installs dependant packages
    . Supports the CommonJS package standard
    . Supports the SemVer package versioning standard
    . Supports using GitHub and NPM as the primary package repository
    . Retrieves packages using the Pak, NPM and Bower catalogs

.SH NICE PARTS
While Pak has a strong feature set, there are some characteristics that make Pak particularly sweet.

    . Fast, fast, fast.
    . Local cache of packages supports fast offline use.
    . Share packages by publishing to a common public catalog.
    . Catalog web portal to search published packages.
    . Pak integrates with the Bower repository to seamlessly download Bower components.
    . Package.json is compatible with nodejs.
    . Retrieve packs from NPM and bower.
    . Easy overriding to tailor packages from NPM and bower.

.PP
.SH BASIC USAGE
.PP
To install packages:
    pak install Endpoints...

Where an ENDPOINT can be the name of a package published in the Pak catalog, NPM or bower catalog, a GitHub repository endpoint, a GitHub account/repository or a path to a local package directory. For example:

    pak install jquery
    pak install pak:jquery
    pak install npm:jquery
    pak install bower:jquery
    pak install embedthis/exp-js
    pak install https://github.com/embedthis/exp-js.git
    pak install git@github.com:embedthis/jquery
    pak install ./my-source/graphics

To uninstall
    pak uninstall Endpoints...

To list installed packages
    pak list

To display package dependencies
    pak depend

To show what packages are present in the cache and where they originated
    pak cached

To download and cache a package but not install in the local directory
    pak cache Name

To prune old versions from the cache
    pak prune

.PP
.SH OVERVIEW
A package is described by a CommonJS package.json file. This provides at a minimum the following properties.
.PP
.RS 5
{
    "name": "Package name - one word"
    "description": "Package description - one line"
    "version": "1.2.3",
    "keywords": [
        "comms", "websockets", "sockets", "ssl",
    ],
    "author": {
        "name": "Your name",
        "email": "Your email",
        "url": "Your web site"
    },
    "bugs": {
        "email": "name@example.com",
        "url": "http://example.com/bugs"
    },
    "license": "GPL",
    "dependencies": {
        "name": "version"
    }
}
.RE
.PP
For more details, see:
    http://package.json.nodejitsu.com
    http://wiki.commonjs.org/wiki/Packages/1.1
    https://npmjs.org/doc/json.html


.SH RUNNING
To run Pak with more verbose trace output, use the [-v] --verbose switch. To run with less trace, use the
[-q] --quiet switch.  To run completely silently except for hard-errors, use --silent.

.SH PUBLISHING
To publish a new package, create a package.json and then run pak inside the directory of the package to be published:

    pak publish

Where NAME is the name of package, REPOSITORY is the GitHub endpoint of the package. You will be prompted to enter a
password to manage the package. You will need this password to modify or retract the package in the future.
Safeguard it well.

.SH CONFIGURATION
On startup, Pak reads configuration from a pakrc file. This file defines the operational configuration for Pak. For example:
 {
    catalogs: {
        pak: {
            list: 'http://embedthis.com/catalog/do/pak/search',
            query: 'http://embedthis.com/catalog/do/pak/search?keywords=${NAME}',
            download: 'https://github.com/${OWNER}/${NAME}/archive/${TAG}.tar.gz',
        },
        bower: {
            list: 'http://bower.herokuapp.com/packages',
            query: 'http://bower.herokuapp.com/packages/${NAME}',
            download: 'https://github.com/${OWNER}/${NAME}/archive/${TAG}.tar.gz',
        },
        npm: {
            query: 'http://registry.npmjs.org/${NAME}',
            download: 'http://registry.npmjs.org/${NAME}/-/${NAME}-${TAG}.tgz',
        }
    },
    "directories": {
        "paks": "paks",
        "pakcache": "~/.paks",
    },
 }

The "catalogs" property defines sites that index and catalog packs. The "paks" directory is the name of the local
directory in which to store packages. The "pakcache" directory defines where to cache packages on the local system.
.PP
Pak locates a valid pakrc file by searching in order:

    pakrc, .pakrc, ../pakrc, ../.pakrc, /etc/pakrc, package.json

.SH COMMANDS

.TP
cache [packages...]
Download and populate the cache with packages.
.TP
cached [packages...]
List packages in the cache.
.TP
config
Show the Pak configuration.
.TP
depend [packages...]
Display installed package dependencies.
.TP
edit key[=value]...
Edit a package description file.
.TP
help ...
Display this Pak usage help.
.TP
info packages...
Display the README for a cached package.
.TP
init [name [version]]
Create a new package.json.
.TP
install packages...
Install a package on the local system. The package name can be a name in an online catalog or it can be a GitHub endpoint
URL or of the form 'account/repositiory'. The package name may have a catalog prefix "pak", "npm" or "bower" to select
a specific catalog to use when locating the package repository endpoint. Use the --write option to update the package.json
dependencies with the install package. Use with the --optional switch to update the optionalDependencies.
.TP
list [packages...]
List the installed packages.
.TP
lockdown
Lockdown the version criteria for all dependencies. This rewrites the
package.json to define a compatible version expression for all installed
dependencies.
.TP
mode
Index in the modes property. The selected property collection is copied up to the top level. This may be used to select
a "debug" or "release" configuration.
.TP
prune [packages...]
Prune named packages.
.TP
publish name endpoint password
Publish a package in the Pak catalog.
.TP
retract name [pass]
Unpublish a package.
.TP
search packages...
Search for packages in the catalogs.
.TP
uninstall
Uninstall an installed package. Use --write to remove from the package dependencies.
.TP
update [packages...]
Update the pak cache with latest available version of the package. This will check with catalogs to determine the most
recent versions of a package and will download the package and save in the cache.
.TP
upgrade [packages...]
Upgrade installed packages with the latest version of the package. This will update the cache if required.
Use --noupdate to upgrade only from the local cache without downloading new versions.
.TP
version [major|minor|patch|other]
Update the version by incrementing the relevant major, minor or patch portion of the version string.
Alternatively, provide an exact version string to set. Without any argument, 'pak version' will print the current
version.

.SH OPTIONS
.TP
\fB\--all URI\fR
Show all versions of a package.

.TP
\fB\--cache directory\fR
Specify the directory to use for the paks cache. This overrides the values specified in the various pakrc
or package.json files.

.TP
\fB\--details URI\fR
Show more package details. Useful with "pak list".

.TP
\fB\--dir directory\fR
Change to the given directory before running.

.TP
\fB\--force\fR
Force the command to continue. This is useful to install or cache a package when dependencies cannot be satisfied.
It is also useful to cache or install an already cached/installed pack. Aliased as -f.

.TOP
\fB\--init\fR
Initialize the directory by creating a package.json file if one does not already exist. The name of the application is
set to the basename of the directory.

.TP
\fB\--log logName[:logLevel]\fR
Specify a file to log internal execution messages. Bit will log execution related trace to the log file. The log level
specifies the desired verbosity of output. Level 0 is the least verbose and level 9 is the most. The '-v' switch is
an alias for '--log stderr:2'.

.TP
\fB\--nodeps\fR
Used to suppress installing or upgrading dependent packages.

.TP
\fB\--optional\fR
Used when installing packages to add them to the 'optionalDependencies' list instead of as a hard dependency.

.TP
\fB\--paks directory\fR
Specify the local "paks" directory in which to install packages. This overrides the values specified in the various pakrc
or package.json files.

.TP
\fB\--password file\fR
Specify the a file containing the password to use when doing "pak publish".

.TP
\fB\--quiet\fR
Run in quiet mode with less verbose otuput. Aliased as -q.

.TP
\fB\--silent\fR
Run in silent mode suppressing all but hard errors. Aliased as -s.

.TP
\fB\--versions URI\fR
Show package version information.

.TP
\fB\--write URI\fR
Write installed packages to package.json dependencies. Use --optional to update optionalDependencies.
When uninstalling, --write will remove the package from the dependencies and update the package.json.

.PP
.SH "REPORTING BUGS"
Report bugs to dev@embedthis.com.
.SH COPYRIGHT
Copyright \(co Embedthis Software. Bit and Ejscript are a trademarks of Embedthis Software.
.br
.SH "SEE ALSO"
http://embedthis.com/pak/
